doc: escape angle brackets in generated markdown#2395
doc: escape angle brackets in generated markdown#2395lawrence3699 wants to merge 1 commit intospf13:mainfrom
Conversation
|
|
There was a problem hiding this comment.
Pull request overview
This PR fixes MDX compilation failures in generated Markdown docs by escaping angle-bracket placeholders in prose fields (Short, Long, and SEE ALSO descriptions), while leaving the fenced UseLine() synopsis unchanged.
Changes:
- Escape angle brackets when emitting
cmd.Shortandcmd.Longinto Markdown prose. - Escape angle brackets in
SEE ALSOlist descriptions (parent/childShort). - Add a regression test covering escaped prose and unescaped fenced
UseLine()output.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 2 comments.
| File | Description |
|---|---|
doc/md_docs.go |
Escapes angle brackets in Markdown prose output for synopsis/see-also descriptions. |
doc/md_docs_test.go |
Adds regression test asserting escaped prose and unchanged fenced UseLine() output. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| } | ||
|
|
||
| func escapeAngleBrackets(s string) string { | ||
| return strings.NewReplacer("<", "\\<", ">", "\\>").Replace(s) |
There was a problem hiding this comment.
escapeAngleBrackets currently escapes both < and >. Escaping > is not needed to prevent MDX JSX parsing (escaping < is sufficient) and it will also change intended Markdown semantics, e.g. a description line starting with > will no longer render as a blockquote. Consider only escaping < (and update the new test expectations accordingly) to minimize formatting regressions.
| return strings.NewReplacer("<", "\\<", ">", "\\>").Replace(s) | |
| return strings.NewReplacer("<", "\\<").Replace(s) |
| func escapeAngleBrackets(s string) string { | ||
| return strings.NewReplacer("<", "\\<", ">", "\\>").Replace(s) | ||
| } |
There was a problem hiding this comment.
escapeAngleBrackets creates a new strings.Replacer on every call. Since GenMarkdownCustom may run across many commands (e.g., GenMarkdownTreeCustom), consider caching the replacer as a package-level var and reusing it to avoid repeated allocations/work.
Fixes #2375.
Angle-bracket placeholders in
Short,Long, andSEE ALSOdescriptions are currently emitted as raw markdown text, so generated docs like<output_path>are parsed as tags by MDX consumers.This escapes those angle brackets in markdown prose while leaving the fenced
UseLine()output unchanged, and adds a regression test for both the synopsis text and theSEE ALSOdescriptions.Validation:
go test ./docgo test ./...@mdx-js/mdx